/*!
 * \file future.hpp
 * \brief 线程池Future异步编程支持
 *
 * \details 提供线程池的Future异步编程模式实现，支持：
 *          - 异步任务结果获取
 *          - 任务执行状态查询
 *          - 同步和超时等待机制
 *          - 任务取消功能
 *          - 类型安全的结果传递
 *          
 *          Future模式是一种重要的异步编程模式，允许：
 *          - 非阻塞地提交任务
 *          - 稍后获取任务执行结果
 *          - 检查任务是否完成
 *          - 等待任务完成或超时
 *          - 取消尚未执行的任务
 *          
 *          适用场景：
 *          - 异步计算任务
 *          - 并行数据处理
 *          - 非阻塞I/O操作
 *          - 响应式编程模式
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */

#ifndef THREADPOOL_FUTURE_HPP_INCLUDED
#define THREADPOOL_FUTURE_HPP_INCLUDED


  
#include "./detail/future.hpp"
#include <boost/utility/enable_if.hpp>

//#include "pool.hpp"
//#include <boost/utility.hpp>

//#include <boost/thread/mutex.hpp>


namespace boost { namespace threadpool
{

  /*!
   * \brief Future异步结果模板类（实验性功能）
   *
   * \details 实验性实现，不建议在生产环境中使用。
   *          
   *          Future类提供异步任务结果的获取机制，允许：
   *          - 非阻塞地获取任务执行状态
   *          - 等待任务完成并获取结果
   *          - 设置超时等待
   *          - 取消任务执行
   *          
   *          这是现代异步编程的核心组件，类似于：
   *          - std::future (C++11)
   *          - JavaScript Promise
   *          - Java CompletableFuture
   *
   * \tparam Result 异步任务的结果类型
   *
   * \warning 这是实验性API，接口可能会发生变化
   * 
   * \see schedule() 函数用于提交异步任务
   *
   */ 


template<class Result> 
class future
{
private:
  shared_ptr<detail::future_impl<Result> > m_impl; //!< Future实现的智能指针

public:
    typedef Result const & result_type;     //!< 指示函数对象的结果类型
    typedef Result future_result_type;      //!< 指示Future的结果类型


public:

  /*!
   * \brief 默认构造函数
   * 
   * \details 创建一个新的Future实例，初始化内部实现。
   *          
   * \note TODO: 移除这个构造函数，因为它创建了不必要的实例
   */
  future()
  : m_impl(new detail::future_impl<future_result_type>()) // TODO remove this
  {
  }

  /*!
   * \brief 内部使用的构造函数
   * \param impl Future实现的共享指针
   * 
   * \details 仅供内部使用，用于从已有的实现创建Future实例。
   *          这通常在schedule()函数中使用。
   */
  future(shared_ptr<detail::future_impl<Result> > const & impl)
  : m_impl(impl)
  {
  }

  /*!
   * \brief 检查任务是否已完成
   * \return 如果任务已完成则返回true，否则返回false
   * 
   * \details 非阻塞地检查异步任务的执行状态。
   *          这个函数立即返回，不会等待任务完成。
   */
  bool ready() const
  {
    return m_impl->ready();
  }

  /*!
   * \brief 等待任务完成
   * 
   * \details 阻塞当前线程直到异步任务完成。
   *          如果任务已经完成，则立即返回。
   *          这是无超时的等待。
   */
  void wait() const
  {
    m_impl->wait();
  }

  /*!
   * \brief 带超时的等待任务完成
   * \param timestamp 等待的截止时间
   * \return 如果任务在超时前完成则返回true，否则返回false
   * 
   * \details 阻塞当前线程直到任务完成或超时。
   *          这对于避免无限等待很有用。
   */
  bool timed_wait(boost::xtime const & timestamp) const
  {
    return m_impl->timed_wait(timestamp);
  }

   /*!
    * \brief 获取任务执行结果（操作符形式）
    * \return 任务的执行结果
    * 
    * \throws thread::cancelation_exception 如果任务被取消
    * \throws ... 任务执行过程中抛出的其他异常
    * 
    * \details 获取异步任务的执行结果。如果任务尚未完成，
    *          此函数会阻塞直到任务完成。
    */
   result_type operator()() // throw( thread::cancelation_exception, ... )
   {
     return (*m_impl)();
   }

   /*!
    * \brief 获取任务执行结果
    * \return 任务的执行结果
    * 
    * \throws thread::cancelation_exception 如果任务被取消
    * \throws ... 任务执行过程中抛出的其他异常
    * 
    * \details 与operator()()功能相同，提供更直观的接口。
    *          获取异步任务的执行结果，如果任务尚未完成会阻塞等待。
    */
   result_type get() // throw( thread::cancelation_exception, ... )
   {
     return (*m_impl)();
   }

   /*!
    * \brief 尝试取消任务
    * \return 如果成功取消则返回true，否则返回false
    * 
    * \details 尝试取消尚未开始执行的任务。
    *          如果任务已经开始执行或已完成，取消操作会失败。
    *          取消成功的任务在调用get()时会抛出取消异常。
    */
   bool cancel()
   {
     return m_impl->cancel();
   }

   /*!
    * \brief 检查任务是否已被取消
    * \return 如果任务已被取消则返回true，否则返回false
    * 
    * \details 查询任务的取消状态。被取消的任务不会执行，
    *          调用get()或operator()()会抛出取消异常。
    */
   bool is_cancelled() const
   {
     return m_impl->is_cancelled();
   }
};





/*!
 * \brief 向线程池提交异步任务并返回Future
 * 
 * \tparam Pool 线程池类型
 * \tparam Function 函数对象类型
 * \param pool 线程池引用
 * \param task 要执行的任务函数
 * \return Future对象，用于获取任务结果
 * 
 * \details 这是Future异步编程的核心函数，它：
 *          1. 创建Future实现对象
 *          2. 将任务包装成Future任务
 *          3. 将任务提交到线程池
 *          4. 返回Future对象供调用者使用
 *          
 *          只有当函数返回类型不是void时才启用此重载。
 *          对于void返回类型，需要使用其他重载。
 *          
 *          使用示例：
 *          \code
 *          pool tp(4);
 *          auto fut = schedule(tp, []() { return 42; });
 *          int result = fut.get(); // 获取结果
 *          \endcode
 * 
 * \note 使用SFINAE技术确保只对非void返回类型启用
 */
template<class Pool, class Function>
typename disable_if < 
  is_void< typename result_of< Function() >::type >,
  future< typename result_of< Function() >::type >
>::type
schedule(Pool& pool, const Function& task)
{
  typedef typename result_of< Function() >::type future_result_type;

  // 创建Future实现和Future对象
  shared_ptr<detail::future_impl<future_result_type> > impl(new detail::future_impl<future_result_type>);
  future <future_result_type> res(impl);

  // 调度Future实现任务
  pool.schedule(detail::future_impl_task_func<detail::future_impl, Function>(task, impl));

  // 返回Future对象
  return res;

/*
 TODO: 旧的实现思路
  if(pool->schedule(bind(&Future::run, future)))
  {
    return future;
  }
  else
  {
    // 构造空的future
    return error_future;
  }
  */
}



} } // namespace boost::threadpool

#endif // THREADPOOL_FUTURE_HPP_INCLUDED

